home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / ztrsna.z / ztrsna
Text File  |  1996-03-14  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZTRSNA - estimate reciprocal condition numbers for specified eigenvalues
  10.      and/or right eigenvectors of a complex upper triangular matrix T (or of
  11.      any matrix Q*T*Q**H with Q unitary)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE ZTRSNA( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S,
  15.                         SEP, MM, M, WORK, LDWORK, RWORK, INFO )
  16.  
  17.          CHARACTER      HOWMNY, JOB
  18.  
  19.          INTEGER        INFO, LDT, LDVL, LDVR, LDWORK, M, MM, N
  20.  
  21.          LOGICAL        SELECT( * )
  22.  
  23.          DOUBLE         PRECISION RWORK( * ), S( * ), SEP( * )
  24.  
  25.          COMPLEX*16     T( LDT, * ), VL( LDVL, * ), VR( LDVR, * ), WORK(
  26.                         LDWORK, * )
  27.  
  28. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  29.      ZTRSNA estimates reciprocal condition numbers for specified eigenvalues
  30.      and/or right eigenvectors of a complex upper triangular matrix T (or of
  31.      any matrix Q*T*Q**H with Q unitary).
  32.  
  33.  
  34. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  35.      JOB     (input) CHARACTER*1
  36.              Specifies whether condition numbers are required for eigenvalues
  37.              (S) or eigenvectors (SEP):
  38.              = 'E': for eigenvalues only (S);
  39.              = 'V': for eigenvectors only (SEP);
  40.              = 'B': for both eigenvalues and eigenvectors (S and SEP).
  41.  
  42.      HOWMNY  (input) CHARACTER*1
  43.              = 'A': compute condition numbers for all eigenpairs;
  44.              = 'S': compute condition numbers for selected eigenpairs
  45.              specified by the array SELECT.
  46.  
  47.      SELECT  (input) LOGICAL array, dimension (N)
  48.              If HOWMNY = 'S', SELECT specifies the eigenpairs for which
  49.              condition numbers are required. To select condition numbers for
  50.              the j-th eigenpair, SELECT(j) must be set to .TRUE..  If HOWMNY =
  51.              'A', SELECT is not referenced.
  52.  
  53.      N       (input) INTEGER
  54.              The order of the matrix T. N >= 0.
  55.  
  56.      T       (input) COMPLEX*16 array, dimension (LDT,N)
  57.              The upper triangular matrix T.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      LDT     (input) INTEGER
  75.              The leading dimension of the array T. LDT >= max(1,N).
  76.  
  77.      VL      (input) COMPLEX*16 array, dimension (LDVL,M)
  78.              If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or
  79.              of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs
  80.              specified by HOWMNY and SELECT. The eigenvectors must be stored
  81.              in consecutive columns of VL, as returned by ZHSEIN or ZTREVC.
  82.              If JOB = 'V', VL is not referenced.
  83.  
  84.      LDVL    (input) INTEGER
  85.              The leading dimension of the array VL.  LDVL >= 1; and if JOB =
  86.              'E' or 'B', LDVL >= N.
  87.  
  88.      VR      (input) COMPLEX*16 array, dimension (LDVR,M)
  89.              If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or
  90.              of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs
  91.              specified by HOWMNY and SELECT. The eigenvectors must be stored
  92.              in consecutive columns of VR, as returned by ZHSEIN or ZTREVC.
  93.              If JOB = 'V', VR is not referenced.
  94.  
  95.      LDVR    (input) INTEGER
  96.              The leading dimension of the array VR.  LDVR >= 1; and if JOB =
  97.              'E' or 'B', LDVR >= N.
  98.  
  99.      S       (output) DOUBLE PRECISION array, dimension (MM)
  100.              If JOB = 'E' or 'B', the reciprocal condition numbers of the
  101.              selected eigenvalues, stored in consecutive elements of the
  102.              array. Thus S(j), SEP(j), and the j-th columns of VL and VR all
  103.              correspond to the same eigenpair (but not in general the j-th
  104.              eigenpair, unless all eigenpairs are selected).  If JOB = 'V', S
  105.              is not referenced.
  106.  
  107.      SEP     (output) DOUBLE PRECISION array, dimension (MM)
  108.              If JOB = 'V' or 'B', the estimated reciprocal condition numbers
  109.              of the selected eigenvectors, stored in consecutive elements of
  110.              the array.  If JOB = 'E', SEP is not referenced.
  111.  
  112.      MM      (input) INTEGER
  113.              The number of elements in the arrays S (if JOB = 'E' or 'B')
  114.              and/or SEP (if JOB = 'V' or 'B'). MM >= M.
  115.  
  116.      M       (output) INTEGER
  117.              The number of elements of the arrays S and/or SEP actually used
  118.              to store the estimated condition numbers.  If HOWMNY = 'A', M is
  119.              set to N.
  120.  
  121.      WORK    (workspace) COMPLEX*16 array, dimension (LDWORK,N+1)
  122.              If JOB = 'E', WORK is not referenced.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          ZZZZTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      LDWORK  (input) INTEGER
  141.              The leading dimension of the array WORK.  LDWORK >= 1; and if JOB
  142.              = 'V' or 'B', LDWORK >= N.
  143.  
  144.      RWORK   (workspace) DOUBLE PRECISION array, dimension (N)
  145.              If JOB = 'E', RWORK is not referenced.
  146.  
  147.      INFO    (output) INTEGER
  148.              = 0: successful exit
  149.              < 0: if INFO = -i, the i-th argument had an illegal value
  150.  
  151. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  152.      The reciprocal of the condition number of an eigenvalue lambda is defined
  153.      as
  154.  
  155.              S(lambda) = |v'*u| / (norm(u)*norm(v))
  156.  
  157.      where u and v are the right and left eigenvectors of T corresponding to
  158.      lambda; v' denotes the conjugate transpose of v, and norm(u) denotes the
  159.      Euclidean norm. These reciprocal condition numbers always lie between
  160.      zero (very badly conditioned) and one (very well conditioned). If n = 1,
  161.      S(lambda) is defined to be 1.
  162.  
  163.      An approximate error bound for a computed eigenvalue W(i) is given by
  164.  
  165.                          EPS * norm(T) / S(i)
  166.  
  167.      where EPS is the machine precision.
  168.  
  169.      The reciprocal of the condition number of the right eigenvector u
  170.      corresponding to lambda is defined as follows. Suppose
  171.  
  172.                  T = ( lambda  c  )
  173.                      (   0    T22 )
  174.  
  175.      Then the reciprocal condition number is
  176.  
  177.              SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )
  178.  
  179.      where sigma-min denotes the smallest singular value. We approximate the
  180.      smallest singular value by the reciprocal of an estimate of the one-norm
  181.      of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be
  182.      abs(T(1,1)).
  183.  
  184.      An approximate error bound for a computed right eigenvector VR(i) is
  185.      given by
  186.  
  187.                          EPS * norm(T) / SEP(i)
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.